Manual for Draw!

MANUAL FOR DRAW V5.2 FOR LINUX

By: Daniel Brodzik

Released April 16, 2005

My e-mail address appears in the section called 'CONTACTING THE AUTHOR'.

LEGAL STUFF

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA OR visit the Free Software Foundation's website at http://www.gnu.org. A copy of this license is included in the file "COPYING".

This software is copylefted. That means that you are given three (3) specific freedoms:

1. The right to use this software freely.

2. The right to modify this software freely.

3. The right to copy and distribute verbatim or modified copies of this program freely.

However, you are *NOT* granted the right to take these rights away from others or put any additional restrictions on it that are not specifically permitted by the GNU GPL document. I have provided it with this program. In other words, if you copy or change this program, then you may NOT alter ANY part of the license agreement!!! Look in the program group in your Start menu for an entry entitled 'License Agreement'. I urge you to thoroughly read that document before doing anything else if you haven't already done so while installing this or another GPL program! Also, I urge you to go to http://www.gnu.org/philosophy/philosophy.html for more information on copylefted programs, and the enemy: proprietary sofware. I think the Free Software Foundation really has a great idea.

SYSTEM REQUIREMENTS

A 386 or newer, Linux, the X Window System (XFree86 v4.3 or later, or XOrg), and fairly recent versions of system libraries.

OPERATION

To install, untar the program into your home directory, cd to it, and type "su -c 'make install'". If you don't have GNU make installed, then copy "draw" (the executable) to your /usr/local/bin directory by typing "su -c 'cp draw /usr/local/bin'". If you want to compile the source yourself, see the section "Developer Information" to find out where to get FreeBASIC.

This version doesn't have the introductory slide show. Start the program by going to a terminal window, "cd"ing to the directory you want to save your images into, and typing "draw". Then, press H for help.

This version of Draw is now going to be the only version in development. I am now doing a lot of work on it. If FreeBASIC for DOS gets graphics support, I will support DOS again. However, since the source code is now tuned for FreeBASIC, which is 32-bit, Draw now requires a 386 or newer.

A few notes about each command:

Arrows -> Move dot – These work only when mouse support is off or the mouse is outside the main window. The cursor is a one-pixel dot that is sometimes hard to see. If you can't see it, try pressing "y" to cycle the colors.
m -> toggle Mouse support – When mouse support is on, the cursor follows your mouse pointer unless the pointer is moved outside the main window. If a mouse button is held down and the mouse is moved, a continuous line or curve will be drawn.
Enter -> Plot a single dot – This puts one dot on-screen where the cursor is.
d -> toggle Draw mode – When this is on, moving the cursor will leave a trail (draw). If you have draw mode on as well as mouse support on, this will leave a trail of dots when you move the pointer around the main window. To draw a continuous line, use your mouse buttons instead.
t -> Text – To enter text, move the cursor to the place that you want the text to show up, and press "t". Type your text followed by Enter.
b -> Draw a box (press f after this to fill) – To use the box, line, and circle tools, move the cursor to the first point, press the tool's letter, and select another point. While you are prompted to select the second point the following keys work: arrows, Enter, Escape, m, f, and o. "m" toggles mouse support, "f" toggles the fill option (which only works with the box and circle tools), and "o" toggles the coordinates display. The coordinates display is a bit different here in that you can also see the distance between the first point and the position of the cursor and whether the fill toggle is on. The coordinates display is temporarily turned off if you had it on before selecting one of these tools so that you can see the directions. The original setting is restored if you didn't change the state before pressing Enter or Esc, but if you turned it on or off, the new setting will stay in effect.
l -> Draw a line – See the notes for "box"
c -> Draw a circle (press f after this to fill) – See the notes for "box"
f -> Fill a region with the current color. This uses the current color as the border. -- The fill command in Draw works a bit differently than the fill command in most other painting programs. In most other painting programs, the fill tool fills the region that has the same color as the part you activate it on. However, in Draw, the fill tool fills in a region that is bordered with the current color. For example, if you draw a closed figure in Draw, the Fill tool fills in that figure, even if the enclosed area has regions of different colors. This can often lead to unexpected results, so be careful, and save your work often!!
F -> Interactive fill. This prompts for a point whose color to use as the border. -- This command is like the other fill command, but it works a bit differently. This one prompts you to select a point whose color you want to use as the border color.
g -> Copy to clipboard (Get) – This tool uses the same second-point input code that the box, line, and circle tools use, but it doesn't draw anything. Instead, it saves the part of the image that lies between the two points you select into the clipboard for use with the next command.
p -> Paste from clipboard (Put) – This pastes the contents of the clipboard at the cursor's position. Nothing special here.
+/- -> Change Color – Self-explanatory
y -> Color cycling on/off – This causes the program to cycle the current color through all the colors. This makes your drawings more colorful. :)
o -> Coordinates on/off – This shows a status display in the information line (the bottom line). The cursor's coordinates are shown, as well as the current drawing color (top dot) and the color of the point below the cursor (bottom dot).
S -> Save file – Lets you save your drawing. Follow the directions given on-screen.
L -> Load file – Lets you load a drawing. Follow the directions given on-screen. Note that drawings saved with Draw 4.2 and earlier will not load properly under this release of Draw.
C -> Clear screen
ESC -> Quit

BACKGROUND

This program was first written in GW-BASIC. Unfortunately, GWBASIC was interpreted. What that means is that I had to load GW-BASIC first and then the source code using a batch file. Then, it was translated into machine language as it was running. That wasn't the best way to run it. Then, I met Amos. He showed me a compiler called PowerBASIC. I decided to get a copy and redo it in PowerBASIC. I switched to Linux, and I was looking for quite a while to find a QuickBASIC-compatible compiler that worked under Linux. I looked for HOURS and found FreeBASIC. The first time I came across it, it wasn't even ready yet. I recently found out that it was in a usable beta form. So, I got to work at trying to compile Draw under Linux. Here's the result—my first program is now available for my favorite OS. Draw is now back under development.

KNOWN ISSUES/BUGS

These are issues/bugs that I discovered while I was testing the program. Please do not report these, since I already know about them! (Duh!) If you find others, then please do not hesitate to e-mail me. If you know how to fix any of these, then please tell me!!

Lack of joystick support: FreeBASIC doesn't support the joystick yet, and, outside of completely re-writing my program to use SDL, I cannot get joystick support to work. (Yes, FreeBASIC supports SDL.)
Printing support is gone for now. Re-implementing it would be a bit hard because CUPS, the most popular print system, likes PostScript output, and I don't know PostScript very well.

THE FUTURE

Here's a list of things I would like to add/do:

Fix the joystick problems. I will have to wait for FreeBASIC to support it before joystick support will work. So, I can add more features, like the following:
Add some drawing tools. For example, I would like to add line, box, fill, circle, and ellipse tools to Draw. (Done!)
Add other features I think of...

I can actually add more features a lot more easily now that my source code is a lot cleaner and now that I've overcome a lot of the other limitations of the original way I wrote the program!

You can check for updates on http://www.winsite.com/free and my website http://www.geocities.com/dosman1986.

DEVELOPER INFORMATION

I have provided a copy of all of the source code in the installation package. When you installed it, the source code was installed in the directory in which you installed DRAW. The source code files are:

draw.bas -> Source for the executable in FreeBASIC, a QuickBASIC-compatible BASIC compiler for Linux, DOS, and Windows. This is intended to be a Linux port, however. I will not make compiling Windows versions a priority due to my disgust at Micro$oft. FreeBASIC is available at http://fbc.sourceforge.net/. Use FreeBASIC v0.13 to compile this program. Do not use FreeBASIC v0.12 to compile the program because it had a couple of serious bugs that caused Draw to freeze.

Makefile -> This is my makefile. To compile the program, run "make". You need GNU make. However, you do not need GCC. To install the program, you can type "sudo make install" (if you have sudo) or "su -c 'make install'" (if you don't have sudo).

If you modify this program, then your new version MUST be copylefted as well! Otherwise, it's a violation of the GNU General Public License. It's illegal to do that, and we don't want to break the law, now do we?

VERSION HISTORY

(NOTE: This only counts released versions!)

v3.3 (November, 2001):

Initial release (program started at v1.0 with a command-line interface! However, I kept improving it and increasing the version number until I finally released it to the public.)

v4.0 (7/1/2003):

Released my program under what I then thought was the GNU General Public License but was really public domain software.
Used Nullsoft's fabulous installer system. This replaced the dumb installer I wrote from scratch in only about five minutes.
It doesn't use GWBASIC and batch files anymore! I don't have to include GWBASIC with it anymore; it's now compiled as an EXE. I used PowerBASIC to compile it. Source code was still a line-numbered mess.
Almost completely rewrote the 'PLEASE READ ME FIRST' document.
Fixed the cursor problems. It used to disappear when you moved it from the corner of the screen.

v4.0a (7/2/2003):

Copylefted the program. This is to prevent people from taking any end-user's rights away. Now it's TRULY copylefted GPL free software!
Added developer information to this file.
Updated the 'Legal stuff' section.
Added a document that was saved from the GNU and Free Software Foundation website about the different types of free and non-free software.
Added shortcuts for the aforementioned document and Draw's license agreement

v4.0b (7/16/2003):

Made some changes to the installation system. Now, when it is run, you no longer see the 'branding text' (i.e., 'Nullsoft Install System v whatever'). Tell me if you like it better now. In addition, the uninstaller is more thorough. Instead of removing files one by one, it now uses wildcards. This means that you should COPY/MOVE ANYTHING YOU HAVE SAVED IN THIS PROGRAM THAT YOU WANT TO KEEP FROM DRAW'S DIRECTORY BEFORE UNINSTALLING!

v4.1 (11/7/2003):

Heavily modified the installer code to make it look cooler and to be more efficient
Made the manual in three formats: Word XP, MHTML, and Acrobat PDF instead of ordinary, boring text format
Removed the line numbers from the source code. Next step: optimizing it. I wanted to release my programs simultaneously for this release due to the very important dedication section.

v4.2 (5/30/2004)

Code overhaul—now things are starting to look better! I even added comments!! Some messages were also added/changed.
Updated the installer for NSIS 2.0 final (was for 2.0b3)—another code overhaul. Some new features were added to the installer while I was updating it.
Made the HTML version of the 'manual' the only version in order to cut down on the size of the distribution, and also to remove the proprietary Micro$oft Word format.
Abandoned Micro$oft Wincrap 98 in favor of Linux and FreeDOS!!! Abandoned Micro$oft Office in favor of OpenOffice.org!!! Read my website, http://www.geocities.com/dosman1986, for more information! I'm free!!! Wa-hoo!! =)
Eliminated the need for the external print-screen program; FirstBASIC allowed me to integrate it into the main program.

v4.2L (2/12/2005)

Incomplete Linux port of version 4.2 thanks to FreeBASIC! Loading, saving, and printing don't work yet, but it is the first version of Draw that does not need any proprietary software at all to build; FreeBASIC is under the GNU General Public License.

v5.0 (2/17/2005)

This is a MAJOR release! Almost everything I have been wanting to implement over the last three or so years is now here! So, here's what's new for this release:

The old 16-bit DOS version of Draw is now discontinued. DOS support will resume if the DOS version of FreeBASIC gets graphics support. Please note that FreeBASIC is a 32-bit BASIC compiler. This means that any future DOS versions of Draw will require a 386 or higher CPU. For these reasons, I will keep my current DOS version of Draw available for download, but please understand that it is discontinued.
Mouse support!!! Yes, it's finally true; Draw supports the mouse. To use it, press M. Then, the cursor will follow your mouse pointer when it is in the Draw window. Hold down any mouse button to draw. Roll your mouse wheel to change colors.
Loading and saving of pictures now works properly under Linux! Please note that pictures saved with the old DOS version of Draw will not be usable under this release because the image format has changed.
This release is the first to do more than 320x200, 4-color graphics! Draw for Linux, as distributed, now supports 640x480, 16 colors. You can change the video mode parameters by getting FreeBASIC from http://fbc.sourceforge.net, modifying the constants in draw.bas to suit the screen mode you want, and recompiling the program. I am considering moving these values to a configuration file.
Text entry on your drawings works better than ever. Now, to enter text, you move the cursor to where you want the text to be, press T, type your text, and then press Enter. In GW-BASIC, this worked by pressing T, moving the cursor around, typing, and pressing ENTER. That no longer worked under FreeBASIC, FirstBASIC, or PowerBASIC, so I had to come up with an alternative for this.
All line numbers have (hopefully) been replaced with labels. This cleans up the code quite a bit.
All obsolete code has been deleted. This included the intro screens, the print routine (which depended on a DOS-only feature), the DOS prompt (which is not needed under a multitasking operating system—use a separate terminal window instead), text mode (it was a total kluge anyway...), and various other things.
Various other code cleanups
Made various changes and fixes to the load and save routines to make them more user-friendly. The save routine asks you if you really want to overwrite an existing file, and the load routine is more intelligent when a file whose name is given doesn't exist or the user presses Enter without typing anything to abort.
The load routine actually restores the existing picture when it is aborted.
You may now save and load pictures with any extension you want or without a filename extension. Previous versions of Draw forced you to use ".bin" for an extension.

v5.1 (2/19/2005)

Two days after release 5.0, here's the next version... Here's what's new:

The arrow keys work again. I learned the proper way to test for the arrow keys in graphics mode in FreeBASIC, so they work again. This time, however, you make diagonal movements by holding down two arrow keys, not by using the numeric keypad's arrows. As a side-effect, the color cycling now works properly with the keyboard.
Added a header file, "scancodes.bi", which adds definitions for the keyboard scan codes to make the program's source code more readable.
Added clipboard support.
Added line, box, and circle drawing tools.
Added a generic subroutine that gets a second point from the user. It is a "lite"r version of the main routine in that most of the cursor handling code is the same, and it has minimal functionality. It is used for the functions that require two points (the clipboard copy function, the line tool, the box tool, and the circle tool). It also has the mouse toggle function and a slightly different coordinate display that shows the distance between the two points and whether the "Fill" toggle is on.
Fixed a mouse wheel-related bug. It seems that the mouse wheel counter reads -1 when the pointer is outside the window, and this was making the color change whenever the pointer left the window. This shouldn't happen anymore.
Updated the help screen to show what functions are actually available.
Made the Load, Save, and Clear functions require an uppercase letter to work (i.e., push shift+the letter), and almost everything else require a lowercase letter. This was done to make the commands easier to remember (e.g., Line and Load both start with L) and to reduce the possibility of accidentally erasing an image by pushing C. Pay attention if you've used Draw before!
A lot more code clean-up.

v5.2 (4/16/2005)

Updated for FreeBASIC 0.13. Only use that version to compile this program. The reason this release took so long was that I was waiting for a bug in v0.12 that kept freezing this program to be fixed. (It affected the mouse support, and I wanted to compile with newer, but working, compiler.)

CREDITS

It's now time to give credit where credit is due:

People and organizations who provided free tools and/or were directly involved in the project:

Daniel Brodzik (all of the programming)
The Free Software Foundation (developed the perfect software licensing and distribution idea, the copylefting idea, and, of course, the GNU General Public License (GPL), the perfect license for free software!)
Andre Victor T. Vicentini (Started the FreeBASIC project. Without FreeBASIC, this program would still be DOS-only!)
Everyone responsible for Linux, for, without this great operating system, this port would not have existed at all!
Anyone that I forgot to mention

People who provided support and encouragement:

You, for downloading and using this program :)
Anyone that I forgot to mention

CONTACTING THE AUTHOR

Questions? Comments? Bug reports? Complaints? Anything? E-mail me at daniel1986@execpc.com (but please keep it clean!) If you abuse my e-mail address, then I will block anything coming from your e-mail address (my e-mail provider lets me put filters on incoming mail). So please do not make me do that. My website is at http://www.geocities.com/gnulinuxman1986.